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REXEC 


The Remote Execution (REXEC) server is a Transmission Control Protocol/Internet Protocol (TCP/IP) 
application that allows a client user to submit system commands to a remote server system. The user’s 
client program sends the user identifier, password, and command to run to the server. The server validates 
the user, runs the requested command, and returns the results of the command to the client. 


Commands submitted to the iSeries host fall into three categories: 


iSeries command processor 
You run iSeries command processor commands by specifying QCAPCMD as the target of the client 
REXEC. 


Qshell command interpreter (OS/400 option 30) 
You can use the Qshell interpreter by specifying qsh as the target of client REXEC. 


"Spawned paths” 


You can run any iSeries program in a "child” (Spawned) job by specifying the complete path to the 
program or shell script as the target of the REXEC command. 


You can work with REXEC server properties through the graphical user interface (GUI) 


for OS/400. 
Use Print this topic] to print out the REXEC articles. 


Print this topic 
To view or download the PDF version, select}REXEC] (about 117 KB or 32 pages). 


To save a PDF on your workstation for viewing or printing: 

Open the PDF in your browser (click the link above). 

In the menu of your browser, click File. 

Click Save As... 

Navigate to the directory in which you would like to save the PDF. 
Click Save. 


oe ONS 


If you need Adobe Acrobat Reader to view or print these PDFs, you can download a copy from the 
(www.adobe.com/prodindex/acrobat/readstep.html) aes ; 


Changing Attributes 


The Change REXEC Attributes (CHGRXCA) command changes the REXEC server attributes. The following 
are two ways to get to this command prompt: 


¢ Specify the CHGRXCA command. 
¢ Select Option 17 on the Configure TCP/IP Applications (CFGTCPAPP) display. 


Note: You must have *IOSYSCFG special authority to make changes to the REXEC attributes with the 
CHGRXCA command. 


Figure 1. Change REXEC Attributes (CHGRXCA) 
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Change REXEC Attributes (CHGRXCA) 


Type choices, press Enter. 


Autostart server . 2 « «<6 « « « *YES *YES, *NO, *SAME 
Number of initial servers Soe 2 1-20, *SAME, *DFT 
Inactivity timeouts 0) = 4 cs 300 1-2147483647, *SAME, *DFT 
Coded character set identifier 00437 1-65533, *SAME, *DFT 
Se 7 


REXEC Command Considerations 


The REXEC server is restricted to running commands that are allowed in batch jobs. The command must 
have «BATCH as one of the Where allowed to run values. 


The maximum length of a command that the REXEC server can process is 4000 bytes. Some REXEC 
clients limit the command to a smaller length. 


For spawned paths, the program that runs in the child process must be either a program object in the 
QSYS.LIB file system (*PGM object) or a shell script. You must specify the path with the proper syntax for 
the file system in which the file resides. 


For Qshell commands, you can put the same commands that you would enter at an interactive command 
line into a non-interactive shell script. 


Selecting a Command Processor 


You can use the REXEC server command processing selection exit program 
(QIBM_QTMX_SVR_SELECT) to select which command processor the REXEC server uses to run the 
submitted command. (If you do not use an exit program, the REXEC server uses the Control Language 
(QCAPCMD) processor.) The allowed command processors are: 

* Control Language (QCAPCMD) 

* Qshell interpreter 


¢ Spawned path (a shell script or program object) 


Because data conversion is optional for the Qshell and spawn options, the exit program also selects 
whether the REXEC server performs ASCII-EBCDIC conversions on the stdin, stdout, and stderr streams. 


REXEC Connection Usage 


The REXEC protocol allows a REXEC client to specify whether to use one or two connections for returning 
data. 


For iSeries CL command processing 


If you choose iSeries CL command processing and two connections, normal output returns on the first 
connection, and error output returns on the second connection. The REXEC server returns all spooled 
data that is written to the default printer file (*PRTF). This includes data that is written to the screen if the 
command is run in an interactive job. Any messages written to the job log return to the client on the 
second connection. 


If the client specifies that all data returns on a single connection, the job log messages are returned first, 
followed by any spooled output. 
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For Qshell and spawned path command processing 


For Qshell or spawned path command processing, the REXEC server by default returns normal output on 
the first connection and error output on the second connection. (The REXEC stdin, stdout, and stderr 
streams are mapped to file descriptors 0, 1, and 2 respectively, and the 
QIBM_USE_DESCRIPTOR_STDIO environment variable is set to Y.) These options allow you to redirect 
input and output. 


Choosing the Qshell command processor sets these environment variables: 
* TERMINAL_TYPE=REMOTE 

¢ PATH=/usr/bin 

¢ LOGNAME= user, where user is the user profile 

* HOME=homedir, where homedir is the user’s home directory 


The child job inherits any other environment variables that the exit program sets. 

Spawned child processes are batch jobs or prestart jobs. They cannot do interactive I/O. See|WebSphere 
Development Studio: ILE C/C++ Programmer's Guide’ for complete details on this support. 
Spooled Output Considerations 


Note: This section applies only to iSeries CL commands. 

The REXEC server overrides the default printer file (*PRTF) to capture spooled output. Any resulting spool 
files are tagged with the user data field set to REXECSVR. After the REXEC server runs the specified 
command, each spooled file with this user data tag is retrieved, returned to the client, and then deleted. If 
more than one spool file is created, the files are processed in the order created, as determined by the 
spool file number. 


If the command or program run through REXEC performs its own print file override and changes the user 
data, the REXEC server is unable to capture and return the resulting spooled data. 


Client Considerations 


The iSeries REXEC client (RUNRMTCMD) uses a single connection for returned data, which is written to a 
spooled file on the client system. 


The UNIX, OS/2, Windows 95, and Windows NT REXEC clients all use two connections, returning the 
normal output to the stdout stream and the error output to the stderr stream. 


The VM REXEC client uses a single connection for the returned data, which is written to the console of 
the user. 


REXEC Server Jobs and Job Names 


REXEC server jobs start when you run the STRTCP command and setthe REXEC AUTOSTART 
parameter to «YES. You can also start REXEC server jobs by running the STRTCPSVR command with a 
SERVER parameter of *REXEC or «ALL. These jobs run in the QGYSWRK subsystem. Their purpose is 
monitoring and processing requests from REXEC client users. The format for the names of these jobs is 
QTRXCnnnnn, where nnnn is a 5-digit decimal number. 


To work with jobs in the QSYSWRK subsystem, including REXEC server jobs, specify the following 
command: 


WRKSBSJOB SBS (QSYSWRK) 
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If you choose to have commands processed by the Qshell command interpreter, you start Qshell is by 
using the spawn() application program interface (API) to create a child job. 


If you choose to have commands interpreted as spawn path names, the REXEC server treats command 
strings as path names and passes them to the spawn() API. Spawned child processes are batch jobs or 
prestart jobs. Shell scripts are allowed for the child process. If you specify a shell script, the appropriate 

shell interpreter program is called. The shell script must be a text file and must contain this format on the 
first line of the file: #!interpreter_path <options>. 


Creating REXEC Server Spooled Job Logs 


The REXEC server automatically writes a server job log to a spooled file when it ends with an error. 


To have a spooled job log produced at the end of each REXEC session and each time the REXEC server 
ends, use the CHGJOBD command, as follows: 


CHGJOBD JOBD(QTCP/QTMXRXCS) LOG(4 00 *SECLVL) 


To obtain a spooled job log only when a server ends, use the CHGJOBD command, as follows: 
CHGJOBD JOBD(QTCP/QTMXRXCS) LOG(4 00 *NOLIST) 


Exit Points for Controlling REXEC Server 


Available exit points give you additional control over the REXEC server. The TCP/IP request validation exit 
point (QIBM_QTMX_SERVER_REQ) provides additional control for restricting an operation. The REXEC 
server command processing selection exit point (QIBM_QTMX_SVR_SELECT) allows you to specify which 
command processor the REXEC server uses for interpreting and running your commands. If you add exit 
programs to both of these exit points, REXEC server first calls the program that you add to 
QIBM_QTMX_SERVER_RE@Q. The TCP/IP server logon exit point (QIBM_QTMX_SVR_LOGON) provides 
additional control over authenticating a user and setting up the user’s environment for the REXEC server. 


Determining Problems with REXEC 


If a problem is detected when using the REXEC server, use the following flow chart to identify the cause 
after using the flow chart for|general TCP/IP problems] The cause lists that follow identify potential 


problems. 
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Issue REXEC 
command 


Connect 
successful? 


No 


Check 
Cause List A 


Logon 
successful? 


Check 
Cause List B 


Command 
successful? 


No 


Check 
Cause List C 


REXEC is working 
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Figure 2. REXEC Server Problem Analysis 


Cause List A 


1. Check to see that the REXEC server is running. If not, start it with the STRTCPSVR 
SERVER(*REXEC) command. 

2. If the message "Connection refused” is returned to the REXEC client, check the exit program 
associated with the exit point QI]BM_QTMX_SERVER_RE@. This exit program has either specified that 


the connection 


should be rejected, returned a value that is not correct for the Allow Operation 


parameter, or ended abnormally. Examine the REXEC server job log for messages. Resolve any 
problems with the exit program and install the corrected version. 


Cause List B 


1. Check your user ID and password by logging on to the system. If you are unable to do so, contact the 
system administrator to verify that your user ID and password are correct. 


2. Check the exit 


program associated with exit point QIBM_QTMX_SERVER_LOGON (if any). This exit 


program has either specified that the connection should be rejected, returned a value this is not correct 
for the Allow Operation parameter, or ended abnormally. Examine the REXEC server job log for 


messages. 


Cause List C 


1. Check for any job log messages returned to the REXEC client. Resolve any indicated problems and try 
the command again. 

2. If the message "Command Rejected” is returned to the REXEC client, check the exit program 
associated with the exit point QI]BM_QTMX_SERVER_RE@. This exit program may be specifying that 
the command should be rejected, returning a value this is not correct for the Allow Operation 
parameter, or ending abnormally. Examine the REXEC server job log for messages. Resolve any 
problems with the exit program and install the corrected version. 


3. Verify that the correct ASCII CCSID is configured for the REXEC server. If not, set the correct CCSID 
with the CHGRXCA command. 
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Materials Required for Reporting REXEC Problems 
Any REXEC problem reported to IBM should include the following: 
¢ Acommunications trace from the time of the failure (Request TCP/IP data only) formatted for ASCII. If 


ou are not familiar with the procedure for collecting a communications trace, see [Communications] 
¢ If the REXEC server has logged software error data, submit this information. 


Note: The system value QGFWERRLOG must be set to *LOG for software error logging to take place. 
If an error occurs while QSFWERRLOG is set to *NOLOG, change the value to *LOG, try to 
recreate the error, and submit the logged software error data. If logged software error data is 
submitted, there is no need to perform a trace of the REXEC server. 


¢ The QTCPIP and any REXEC server job logs. 


Getting a Copy of a REXEC Server Job Log 
To have the REXEC server save job logs, see|“Creating REXEC Server Spooled Job Logs” on page 4 


Tracing the REXEC Server 


The REXEC server can be traced by creating a data area. Note that running the REXEC server with trace 
running may cause a significant performance impact. 


To trace the REXEC server: 


1. Create the data area using the following command: CRTDTAARA DTAARA(QUSRSYS/QTMXRXCDBG) 
TYPE(*LGL) LEN(1) 


2. Perform the REXEC operation that you want to trace. 
3. Delete the data area using the following command: DLTDTAARA DTAARA (QUSRSYS/QTMXRXCDBG) 
4. Enter the following command to find the output queue: 

DSPSYSVAL QPRTDEV 

For example, the following display appears: 


Display System Value 


System value .....: QPRIDEV 
Description .... .: Printer device description 
Printer device... .:  PRTO1 Name 


Figure 3. Display System Value Display 


The printer device is also the name of the default system output queue. 
5. Record the name of the printer device. In this example, PRT01 is the printer device. 
6. Press F12 (Cancel) to return to the display where you entered the DSPSYSVAL command. 
7. Type the following command: 

WRKOUTQ OUTQ(printer-device) 


Replace printer-device with the printer device recorded in the previous display. PRTO1 is the output 
queue in this example. For example, the following display appears: 
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Work with Output Queue 
Queue: PRTO1 Library: QGPL Status: RLS 
Type options, press Enter. 
1=Send 2=Change 3=Hold 4=Delete 5=Display 6=Release 7=Messages 


8=Attributes 9=Work with printing status 
Opt File User User Data Sts Pages Copies Form Type Pty 
_—  QTCPPRT QTCP QTMSMTP HLD 46 1 *STD 5 
QPSRVTRC QSECOFR HLD 44 #1 *STD 5 


Figure 4. Work with Output Queue Display 


8. Press F18 (Bottom) to get to the bottom of the spooled file list if More... appears on the display. 


9. Find the last file named QPSRVTRC with the same user as the user who was logged on the REXEC 
server when the trace was created. 


10. Press F11 (View 2) to view the date and time of the file you want to work with. 
11. Verify that you are working with the most recent spooled file, QESRVTRC. 


12. Indicate in the problem report that the trace was tried and it failed. Send whatever trace information 
there is with the problem report. 
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